home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / Log / Message / Item.pm < prev    next >
Encoding:
Perl POD Document  |  2009-06-26  |  4.6 KB  |  193 lines
  1. package Log::Message::Item;
  2.  
  3. use strict;
  4. use Params::Check qw[check];
  5. use Log::Message::Handlers;
  6.  
  7. ### for the messages to store ###
  8. use Carp ();
  9.  
  10. BEGIN {
  11.     use vars qw[$AUTOLOAD $VERSION];
  12.  
  13.     $VERSION    =   $Log::Message::VERSION;
  14. }
  15.  
  16. ### create a new item.
  17. ### note that only an id (position on the stack), message and a reference
  18. ### to its parent are required. all the other things it can fill in itself
  19. sub new {
  20.     my $class   = shift;
  21.     my %hash    = @_;
  22.  
  23.     my $tmpl = {
  24.         when        => { no_override    => 1,   default    => scalar localtime },
  25.         id          => { required       => 1    },
  26.         message     => { required       => 1    },
  27.         parent      => { required        => 1    },
  28.         level       => { default        => ''   },      # default may be conf dependant
  29.         tag         => { default        => ''   },      # default may be conf dependant
  30.         longmess    => { default        => _clean(Carp::longmess()) },
  31.         shortmess   => { default        => _clean(Carp::shortmess())},
  32.     };
  33.  
  34.     my $args = check($tmpl, \%hash) or return undef;
  35.  
  36.     return bless $args, $class;
  37. }
  38.  
  39. sub _clean { map { s/\s*//; chomp; $_ } shift; }
  40.  
  41. sub remove {
  42.     my $item = shift;
  43.     my $self = $item->parent;
  44.  
  45.     return splice( @{$self->{STACK}}, $item->id, 1, undef );
  46. }
  47.  
  48. sub AUTOLOAD {
  49.     my $self = $_[0];
  50.  
  51.     $AUTOLOAD =~ s/.+:://;
  52.  
  53.     return $self->{$AUTOLOAD} if exists $self->{$AUTOLOAD};
  54.  
  55.     local $Carp::CarpLevel = $Carp::CarpLevel + 3;
  56.  
  57.     {   no strict 'refs';
  58.         return *{"Log::Message::Handlers::${AUTOLOAD}"}->(@_);
  59.     }
  60. }
  61.  
  62. sub DESTROY { 1 }
  63.  
  64. 1;
  65.  
  66. __END__
  67.  
  68. =pod
  69.  
  70. =head1 NAME
  71.  
  72. Log::Message::Item  - Message objects for Log::Message
  73.  
  74. =head1 SYNOPSIS
  75.  
  76.     # Implicitly used by Log::Message to create Log::Message::Item objects
  77.  
  78.     print "this is the message's id: ",     $item->id;
  79.  
  80.     print "this is the message stored: ",   $item->message;
  81.  
  82.     print "this is when it happened: ",     $item->when;
  83.  
  84.     print "the message was tagged: ",       $item->tag;
  85.  
  86.     print "this was the severity level: ",  $item->level;
  87.  
  88.     $item->remove;  # delete the item from the stack it was on
  89.  
  90.     # Besides these methods, you can also call the handlers on
  91.     # the object specificallly.
  92.     # See the Log::Message::Handlers manpage for documentation on what
  93.     # handlers are available by default and how to add your own
  94.  
  95.  
  96. =head1 DESCRIPTION
  97.  
  98. Log::Message::Item is a class that generates generic Log items.
  99. These items are stored on a Log::Message stack, so see the Log::Message
  100. manpage about details how to retrieve them.
  101.  
  102. You should probably not create new items by yourself, but use the
  103. storing mechanism provided by Log::Message.
  104.  
  105. However, the accessors and handlers are of interest if you want to do
  106. fine tuning of how your messages are handled.
  107.  
  108. The accessors and methods are described below, the handlers are
  109. documented in the Log::Message::Handlers manpage.
  110.  
  111. =head1 Methods and Accessors
  112.  
  113. =head2 remove
  114.  
  115. Calling remove will remove the object from the stack it was on, so it
  116. will not show up any more in subsequent fetches of messages.
  117.  
  118. You can still call accessors and handlers on it however, to handle it
  119. as you will.
  120.  
  121. =head2 id
  122.  
  123. Returns the internal ID of the item. This may be useful for comparing
  124. since the ID is incremented each time a new item is created.
  125. Therefore, an item with ID 4 must have been logged before an item with
  126. ID 9.
  127.  
  128. =head2 when
  129.  
  130. Returns the timestamp of when the message was logged
  131.  
  132. =head2 message
  133.  
  134. The actual message that was stored
  135.  
  136. =head2 level
  137.  
  138. The severity type of this message, as well as the name of the handler
  139. that was called upon storing it.
  140.  
  141. =head2 tag
  142.  
  143. Returns the identification tag that was put on the message.
  144.  
  145. =head2 shortmess
  146.  
  147. Returns the equivalent of a C<Carp::shortmess> for this item.
  148. See the C<Carp> manpage for details.
  149.  
  150. =head2 longmess
  151.  
  152. Returns the equivalent of a C<Carp::longmess> for this item, which
  153. is essentially a stack trace.
  154. See the C<Carp> manpage for details.
  155.  
  156. =head2 parent
  157.  
  158. Returns a reference to the Log::Message object that stored this item.
  159. This is useful if you want to have access to the full stack in a
  160. handler.
  161.  
  162. =head1 SEE ALSO
  163.  
  164. L<Log::Message>, L<Log::Message::Handlers>, L<Log::Message::Config>
  165.  
  166. =head1 AUTHOR
  167.  
  168. This module by
  169. Jos Boumans E<lt>kane@cpan.orgE<gt>.
  170.  
  171. =head1 Acknowledgements
  172.  
  173. Thanks to Ann Barcomb for her suggestions.
  174.  
  175. =head1 COPYRIGHT
  176.  
  177. This module is
  178. copyright (c) 2002 Jos Boumans E<lt>kane@cpan.orgE<gt>.
  179. All rights reserved.
  180.  
  181. This library is free software;
  182. you may redistribute and/or modify it under the same
  183. terms as Perl itself.
  184.  
  185. =cut
  186.  
  187. # Local variables:
  188. # c-indentation-style: bsd
  189. # c-basic-offset: 4
  190. # indent-tabs-mode: nil
  191. # End:
  192. # vim: expandtab shiftwidth=4:
  193.